home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Applications 2004 May / SGI IRIX 6.5 Applications 2004 May.iso / dist / java3d.idb / usr / demos / java / j3d / programs / examples / VirtualInputDevice / README.z / README
Encoding:
Text File  |  2003-08-08  |  10.7 KB  |  235 lines
  1. /*
  2.  *    @(#)README 1.5 01/06/20 16:19:00
  3.  *
  4.  * Copyright (c) 1996-2001 Sun Microsystems, Inc. All Rights Reserved.
  5.  *
  6.  * Redistribution and use in source and binary forms, with or without
  7.  * modification, are permitted provided that the following conditions
  8.  * are met:
  9.  *
  10.  * - Redistributions of source code must retain the above copyright
  11.  *   notice, this list of conditions and the following disclaimer.
  12.  *
  13.  * - Redistribution in binary form must reproduce the above copyright
  14.  *   notice, this list of conditions and the following disclaimer in
  15.  *   the documentation and/or other materials provided with the
  16.  *   distribution.
  17.  *
  18.  * Neither the name of Sun Microsystems, Inc. or the names of
  19.  * contributors may be used to endorse or promote products derived
  20.  * from this software without specific prior written permission.
  21.  *
  22.  * This software is provided "AS IS," without a warranty of any
  23.  * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
  24.  * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
  25.  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
  26.  * EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES
  27.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  28.  * DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN
  29.  * OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR
  30.  * FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR
  31.  * PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF
  32.  * LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE SOFTWARE,
  33.  * EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  34.  *
  35.  * You acknowledge that Software is not designed,licensed or intended
  36.  * for use in the design, construction, operation or maintenance of
  37.  * any nuclear facility.
  38.  */
  39.  
  40.         Java 3D (TM) Input Device Driver Development Guide
  41.                
  42. Topics
  43.  
  44.   * Write Once, Run Anywhere (TM)
  45.   * Overview of the InputDevice and Sensor APIs
  46.   * Recipe for an Application Program that Uses Input Devices
  47.   * Location for Installation of Device Drivers
  48.   * Using a Preexistent Native Driver
  49.   * Package Naming Conventions
  50.   * Device Driver Constructor
  51.   * Driver Scheduling and Blocking Semantics 
  52.  
  53.  
  54. Write Once, Run Anywhere
  55.  
  56. Platform independence is the cornerstone of the Java (TM) platform.
  57. This vision now extends to external input devices as well.  The
  58. overarching goal of the Java 3D input device architecture is to enable
  59. Java programs that use devices to run in a platform independent
  60. manner.  
  61.  
  62. We encourage developers to use Java APIs for their drivers.  APIs such
  63. as the javax.comm API allow platform independent access to serial and
  64. parallel ports.  However, even if a driver is partially written with
  65. native code, the Java 3D InputDevice interface is layered on top of the
  66. driver such that once the native portion of the driver has been
  67. installed into the local JRE, the application code is platform
  68. independent.  
  69.  
  70. In a future release, the Java 3D team is going to release a registry
  71. mechanism that will reside in the JRE as part of the Java 3D
  72. installation and allow registration of device drivers.  The
  73. SimpleUniverse utility will be modified to allow querying of devices by
  74. generic characteristics, and will subsequently look up and instantiate
  75. the appropriate device driver registered with the registry mechanism.
  76. The Java 3D team also expects to release a set of generic mappings for
  77. devices.  This will enable applications to count on the same behavior
  78. from different drivers for similar types of devices.  There will also
  79. be personalized profiles that enable a user to specify device mappings
  80. for features like dominant hand preference and eye position.  
  81.  
  82.  
  83. Overview of the InputDevice and Sensor APIs
  84.  
  85. Java 3D abstracts the concept of a device via the InputDevice
  86. interface.  The developer's implementation of the InputDevice interface
  87. is layered on top of the device driver.  The device may be a real
  88. device such as a joystick or it may be a virtual device such as a piece
  89. of Java code that does transform calculations.
  90.  
  91. A device sends data back to Java 3D by placing values into Sensor
  92. objects which the device code manages and updates.  The Sensor class
  93. encapsulates a transform and a timestamp.  The transform is specified
  94. in the TrackerBase coordinate system.
  95.  
  96. Java 3D schedules calls to the device's pollAndProcessInput routine,
  97. which is a method in the InputDevice interface.  This method is
  98. responsible for updating the devices sensor values.  The sensors'
  99. values and time stamps are read by a user's behavior code and/or each
  100. frame (by the Java 3D implementation) when head tracking is enabled.
  101. There are several options for scheduling, and they are detailed in the
  102. InputDevice javadoc and in the section below entitled "Driver
  103. Scheduling and Blocking Semantics."
  104.  
  105. Please read the javadocs for InputDevice and Sensor for more detailed
  106. information.  There is also a sample program in the Java 3D release
  107. called VirtualInputDevice, which implements these concepts in Java code.
  108.  
  109.  
  110. Recipe for an Application Program that Uses Input Devices
  111.  
  112. Please see the Java 3D example program in the examples directory called
  113. VirtualInputDevice for an example of using this code recipe:
  114.   1) Implement the InputDevice interface with a class of your own
  115.   2) Call the device's constructor from your main program
  116.   3) Call initialize() on the device
  117.   4) Call PhysicalEnvironment.addInputDevice(InputDevice) or if you are
  118.      using SimpleUniverse, call SimpleUniverse.getViewer().
  119.      getPhysicalEnvironment().addInputDevice(InputDevice)
  120.   5) Assuming you want to modify the viewer's transform with the device:
  121.      add a WakeupOnElapsedFrames behavior to your scene graph that wakes
  122.      up every frame and in the processStimulus method modify the view 
  123.      transform with the transform you pull out of Sensor.getRead.
  124.     
  125. In a future release, it will be possible to replace steps 2, 3, & 4 with
  126. a single method call to the SimpleUniverse utility. 
  127.      
  128.  
  129. Location for Installation of Device Drivers
  130.  
  131. There are two suggested ways to package and distribute drivers.
  132.  
  133. If a driver is written entirely in Java and if it is tightly coupled
  134. with a particular application without the expectation of reuse in other
  135. applications, then it should be bundled and distributed with the
  136. application itself.
  137.  
  138. If a driver is not associated with any particular application program,
  139. if it contains any native code, or if it is expected to be used by more
  140. than one application program, then it should be installed directly into
  141. the end user's local JRE.  It is expected that most drivers for real
  142. devices fall into this category.  On the Solaris platform, the Java
  143. portion of the driver should be installed into jre/lib/ext as a
  144. uniquely named jar file and if there is native code it should be
  145. compiled into a shared object and installed into jre/lib/sparc.  On the
  146. Win32 platform, the Java portion of the driver should be installed into
  147. jre\lib\ext as a uniquely named jar file and if there is native code it
  148. should be compiled into a standard dynamically linked library (dll) and
  149. installed into jre\bin.  
  150.  
  151.  
  152. Using a Preexistent Native Driver
  153.  
  154. It is possible to make a Java 3D driver out of a preexistent native
  155. driver.  In order to do this, you need to create an InputDevice
  156. interface that uses JNI to access the associated native driver methods
  157. whenever the corresponding InputDevice interface method is called from
  158. Java 3D.  The native portion of the driver must be installed into the
  159. target JRE.
  160.  
  161.  
  162. Package Naming Conventions
  163.  
  164. All device drivers that are installed into the JRE should be part of a
  165. package that follows both standard Java and Java 3D naming
  166. conventions.  For instance, an input device driver should be placed
  167. into a package called
  168. com.<company_name>.j3d.drivers.input.<device_name>.  The package should
  169. be jarred up into a jar file that has a unique name.
  170.  
  171. Any native .so or .dll files installed into the JRE should be uniquely
  172. named.
  173.  
  174.  
  175. Device Driver Constructor
  176.  
  177. The constructor arguments for a device driver must be an array of
  178. strings.  So a driver should have a single public constructor that
  179. takes an array of strings.  The idea behind this requirement is that
  180. eventually the Java 3D registry will contain an array of string
  181. arguments to be sent to the device constructor at instantiation time.
  182. The SimpleUniverse API will also make a provision for optional String
  183. arguments to be added to the array of String arguments found in the
  184. registry.
  185.  
  186.  
  187. Driver Scheduling and Blocking Semantics
  188.  
  189. When a device is registered with Java 3D via the
  190. PhysicalEnvironment.addInputDevice(InputDevice) method call,
  191. InputDevice.getProcessingMode() is called on the registered device.
  192. This method should return one of the three processing modes defined in
  193. the InputDevice interface:  BLOCKING, NON_BLOCKING, and DEMAND_DRIVEN.
  194.  
  195.   BLOCKING signifies that the driver for a device is a blocking driver
  196.   and that it should be scheduled for regular reads by Java 3D. A
  197.   blocking driver is defined as a driver that can cause the thread
  198.   accessing the driver (the Java 3D implementation thread calling the
  199.   pollAndProcessInput method) to block while the data is being accessed
  200.   from the driver.
  201.  
  202.   NON_BLOCKING signifies that the driver for a device is a non-blocking
  203.   driver and that it should be scheduled for regular reads by Java 3D.
  204.   A non-blocking driver is defined as a driver that does not cause the
  205.   calling thread to block while data is being retrieved from the
  206.   driver.  If no data is available from the device, pollAndProcessInput
  207.   should return without updating the sensor read value.
  208.  
  209.   DEMAND_DRIVEN signifies that the Java 3D implementation should not
  210.   schedule regular reads on the sensors of this device; the Java 3D
  211.   implementation will only call pollAndProcessInput when one of the
  212.   device's sensors' getRead methods is called. A DEMAND_DRIVEN driver
  213.   must always provide the current value of the sensor on demand
  214.   whenever pollAndProcessInput is called. This means that DEMAND_DRIVEN
  215.   drivers are non-blocking by definition.
  216.  
  217. It is important that you correctly classify your driver.  If it is a
  218. NON_BLOCKING driver, most Java 3D implementations will choose to add
  219. inertia inside the scheduling thread to avoid starvation of the other
  220. Java 3D threads.  If it is a BLOCKING driver, most Java 3D
  221. implementations will choose to spawn a separate scheduling thread for
  222. each BLOCKING device.  If your driver is a DEMAND_DRIVEN driver, your
  223. driver must always provide the current value upon request along with
  224. the current time stamp.
  225.  
  226. When running drivers with the Solaris operating system using the
  227. Solaris reference 1.2 JRE and green threads, you should be aware that
  228. there is a bug that forces all drivers to be BLOCKING.  Thus, you
  229. should be careful to always use native threads on the Solaris reference
  230. 1.2 JRE in order to get the expected behavior.  This is not an issue
  231. with the Solaris 1.2 Performance JRE release, which is native threads
  232. only.
  233.  
  234.  
  235.